feat: add experimental AgentConfig with comprehensive tool management #935

mr-lee · 2025-09-26T20:29:30Z

Resuming #865

Description

Add AgentConfig class for loading configuration from JSON files or dicts
Support model, prompt, and tools configuration options

Goal of this feature:

Start the centralization of serializing the agent config from a file. This currently exists in the tools repo, for spawning sub-agents: https://github.com/strands-agents/tools/blob/main/src/strands_tools/utils/models/model.py
- More strands features will be represented in this feature in follow up pull requests
- We have at least one more upcoming feature that will take advantage of this feature
Make sharing of agents easier: This isnt the most readable format, but we can convert a front matter markdown to a json dict, and then validate the schema using this definition in the future

Usage example

For basic usage with the default set of tools available to choose from the config: file_read, editor, http_request, use_agent, and shell

from strands.experimental import config_to_agent

agent = config_to_agent({"model": "test-model", "prompt": "Test prompt", "tools": ["strands_tools.file_read", "strands_tools.shell"]}, description="My custom description") # everything after config arg is passed to the agent constructor as kwargs

You can also load a config from a file:

from strands.experimental import AgentConfig

config = AgentConfig("file://path/to/local/config) # Config gets loaded into dict
agent = config.to_agent() # kwargs are passed to the agent init

Documentation PR

strands-agents/docs#252

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

I ran hatch run prepare

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

awsarron

proposed interface during experimental:

from strands.experimental import config_to_agent

agent = config_to_agent("/path/to/amazing-agent.json")

agent("do the thing")

potential interface for non-experimental in future releases:

from strands import config_to_agent

agent = config_to_agent("/path/to/amazing-agent.json")

agent("do the thing")

example amazing-agent.json definition of tools:

{
  // ...
  tools: ["strands_tools.file_read", "my_app.tools.cake_tool", "/path/to/another_tool.py"]
}

strands supports loading tools from python modules and filepaths:

sdk-python/src/strands/tools/registry.py

Lines 57 to 105 in eef11cc

    
           def add_tool(tool: Any) -> None: 
        
               # Case 1: String file path 
        
               if isinstance(tool, str): 
        
                   # Extract tool name from path 
        
                   tool_name = os.path.basename(tool).split(".")[0] 
        
                   self.load_tool_from_filepath(tool_name=tool_name, tool_path=tool) 
        
                   tool_names.append(tool_name) 
        
               # Case 2: Dictionary with name and path 
        
               elif isinstance(tool, dict) and "name" in tool and "path" in tool: 
        
                   self.load_tool_from_filepath(tool_name=tool["name"], tool_path=tool["path"]) 
        
                   tool_names.append(tool["name"]) 
        
               # Case 3: Dictionary with path only 
        
               elif isinstance(tool, dict) and "path" in tool: 
        
                   tool_name = os.path.basename(tool["path"]).split(".")[0] 
        
                   self.load_tool_from_filepath(tool_name=tool_name, tool_path=tool["path"]) 
        
                   tool_names.append(tool_name) 
        
               # Case 4: Imported Python module 
        
               elif hasattr(tool, "__file__") and inspect.ismodule(tool): 
        
                   # Get the module file path 
        
                   module_path = tool.__file__ 
        
                   # Extract the tool name from the module name 
        
                   tool_name = tool.__name__.split(".")[-1] 
        
                   # Check for TOOL_SPEC in module to validate it's a Strands tool 
        
                   if hasattr(tool, "TOOL_SPEC") and hasattr(tool, tool_name) and module_path: 
        
                       self.load_tool_from_filepath(tool_name=tool_name, tool_path=module_path) 
        
                       tool_names.append(tool_name) 
        
                   else: 
        
                       function_tools = self._scan_module_for_tools(tool) 
        
                       for function_tool in function_tools: 
        
                           self.register_tool(function_tool) 
        
                           tool_names.append(function_tool.tool_name) 
        
                       if not function_tools: 
        
                           logger.warning("tool_name=<%s>, module_path=<%s> | invalid agent tool", tool_name, module_path) 
        
               # Case 5: AgentTools (which also covers @tool) 
        
               elif isinstance(tool, AgentTool): 
        
                   self.register_tool(tool) 
        
                   tool_names.append(tool.tool_name) 
        
               # Case 6: Nested iterable (list, tuple, etc.) - add each sub-tool 
        
               elif isinstance(tool, Iterable) and not isinstance(tool, (str, bytes, bytearray)): 
        
                   for t in tool: 
        
                       add_tool(t) 
        
               else: 
        
                   logger.warning("tool=<%s> | unrecognized tool specification", tool)

for the initial implementation in this PR we could do something like:

def config_to_agent(filepath: str) -> Agent:
    # pseudo code
    parsed_config = JSON.loads(filepath)
    tools_list = []
    for tool in parsed_config["tools"]:
        tool_arg = tool
        if not is_filepath(tool):
            try:
                tool_arg = importlib.import_module(tool)
            except ImportError as e:
                # handle tool not a file and not a module
        tools_list.append(tool_arg)
    return Agent(tools=tools_list)

src/strands/experimental/agent_config.py

tests/strands/experimental/test_agent_config.py

src/strands/experimental/agent_config.py

- Add AgentConfig class for declarative agent configuration via JSON/dict - Support file:// prefix for loading configurations from JSON files - Implement ToolRegistry integration with automatic default tool loading - Add raise_exception_on_missing_tool parameter for flexible error handling - Support tool selection from registry via tool names in config - Add comprehensive test coverage for all configuration scenarios - Move hook events from experimental to production with updated names - Add OpenAI model provider enhancements and Gemini model improvements - Update event loop and tool executors to use production hook events 🤖 Assisted by Amazon Q Developer

- Reset experimental/__init__.py to not import AgentConfig by default - This may resolve import issues in CI environments - AgentConfig can still be imported directly from strands.experimental.agent_config 🤖 Assisted by Amazon Q Developer

@tool

- Move JSON schema back to inline variable for simplicity - Add comprehensive tool validation with helpful error messages - Validate tools can be loaded as files, modules, or @tool functions - Add clear documentation about code-based instantiation limitations - Update module docstring and function comments with usage patterns - Add test for tool validation error messages - Remove schemas directory (no longer needed) 🤖 Assisted by Amazon Q Developer

@tool

- Fix error message for missing modules to be more descriptive - Remove redundant 'to properly import this tool' text from error messages - Add specific error messages for missing modules vs missing functions - Add unit tests for each error case: - Invalid tool (not file/module/@tool) - Missing module (module doesn't exist) - Missing function (function not found in existing module) - All 17 tests passing with better error coverage 🤖 Assisted by Amazon Q Developer

- Change error message from 'Tool X not found' to 'Module X not found' - More accurate since we're trying to import it as a module at this point - Maintains existing test compatibility and error handling logic 🤖 Assisted by Amazon Q Developer

- Revert previous change from 'Module X not found' back to 'Tool X not found' - Keep original error message format as requested 🤖 Assisted by Amazon Q Developer

codecov · 2025-10-08T19:57:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

src/strands/experimental/agent_config.py

src/strands/experimental/__init__.py

src/strands/experimental/agent_config.py

awsarron

Some follow-ups:

Document in code (docstrings) and docs page that it only supports bedrock model ID parameters
Document using other model providers (change agent.model after transformation)
Track a task for supporting non-bedrock model providers
Track a task for moving from experimental to production-ready

Feedback addressed

Unshure · 2025-10-21T19:59:13Z

Some follow-ups:

* Document in code (docstrings) and docs page that it only supports bedrock model ID parameters

* Document using other model providers (change `agent.model` after transformation)

* Track a task for supporting non-bedrock model providers

* Track a task for moving from experimental to production-ready

Updated the docs to reflect the model provider specification. I also created a follow up task for supporting more model providers: #1064

Here is the task for moving it out of experimental: #1065

mr-lee had a problem deploying to auto-approve September 26, 2025 20:29 — with GitHub Actions Failure

mr-lee had a problem deploying to auto-approve September 26, 2025 20:36 — with GitHub Actions Failure

mr-lee had a problem deploying to auto-approve September 26, 2025 20:46 — with GitHub Actions Failure

mr-lee temporarily deployed to auto-approve September 26, 2025 20:49 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 26, 2025 20:53 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 26, 2025 20:56 — with GitHub Actions Inactive

This was referenced Sep 26, 2025

Add agent configuration support with JSON/dict configs and tool name resolution v2 #934

Closed

Add agent configuration support with JSON/dict configs and tool name resolution #865

Closed

awsarron requested changes Sep 26, 2025

View reviewed changes

mr-lee temporarily deployed to auto-approve September 26, 2025 22:34 — with GitHub Actions Inactive

mr-lee force-pushed the feature/agent-config-squashed branch from 832b290 to f372666 Compare September 26, 2025 22:34

mr-lee temporarily deployed to auto-approve September 26, 2025 22:35 — with GitHub Actions Inactive

mr-lee had a problem deploying to auto-approve September 26, 2025 22:38 — with GitHub Actions Failure

mr-lee force-pushed the feature/agent-config-squashed branch from 27bb82f to c2d1baa Compare September 26, 2025 22:40

mr-lee temporarily deployed to auto-approve September 26, 2025 22:40 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 26, 2025 22:41 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 26, 2025 22:42 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 26, 2025 22:48 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 26, 2025 23:02 — with GitHub Actions Inactive

mr-lee had a problem deploying to auto-approve September 26, 2025 23:03 — with GitHub Actions Failure

mr-lee temporarily deployed to auto-approve September 27, 2025 00:39 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 27, 2025 00:44 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 27, 2025 00:47 — with GitHub Actions Inactive

mr-lee temporarily deployed to auto-approve September 27, 2025 00:48 — with GitHub Actions Inactive

Unshure previously requested changes Sep 27, 2025

View reviewed changes

Unshure self-assigned this Sep 29, 2025

cagataycali reviewed Oct 2, 2025

View reviewed changes

src/strands/experimental/agent_config.py Show resolved Hide resolved

cagataycali reviewed Oct 2, 2025

View reviewed changes

src/strands/experimental/agent_config.py Show resolved Hide resolved

mrlee-amazon added 2 commits October 8, 2025 15:55

mrlee-amazon added 4 commits October 8, 2025 15:55

revert: change error message back to reference tool

cb507dd

- Revert previous change from 'Module X not found' back to 'Tool X not found' - Keep original error message format as requested 🤖 Assisted by Amazon Q Developer

Unshure force-pushed the feature/agent-config-squashed branch from da9ff2e to cb507dd Compare October 8, 2025 19:55

Unshure temporarily deployed to auto-approve October 8, 2025 19:56 — with GitHub Actions Inactive

Unshure temporarily deployed to auto-approve October 8, 2025 20:38 — with GitHub Actions Inactive

Unshure force-pushed the feature/agent-config-squashed branch from 5f3c0a9 to 64a31ab Compare October 8, 2025 20:49

Unshure temporarily deployed to auto-approve October 8, 2025 20:50 — with GitHub Actions Inactive

Unshure force-pushed the feature/agent-config-squashed branch from 64a31ab to 27cef45 Compare October 8, 2025 20:58

Unshure had a problem deploying to auto-approve October 8, 2025 20:58 — with GitHub Actions Failure

feat: use agent tool loading logic

9f33f62

Unshure force-pushed the feature/agent-config-squashed branch from 27cef45 to 9f33f62 Compare October 8, 2025 21:04

Unshure temporarily deployed to auto-approve October 8, 2025 21:04 — with GitHub Actions Inactive

dbschmigelski reviewed Oct 9, 2025

View reviewed changes

src/strands/experimental/agent_config.py Show resolved Hide resolved

src/strands/experimental/agent_config.py Show resolved Hide resolved

src/strands/experimental/__init__.py Show resolved Hide resolved

zastrowm previously requested changes Oct 9, 2025

View reviewed changes

src/strands/experimental/agent_config.py Show resolved Hide resolved

src/strands/experimental/agent_config.py Show resolved Hide resolved

Unshure had a problem deploying to auto-approve October 19, 2025 13:39 — with GitHub Actions Failure

fix: address pr comments

6ca10ce

Unshure force-pushed the feature/agent-config-squashed branch from 97abdb5 to 6ca10ce Compare October 19, 2025 13:39

Unshure had a problem deploying to auto-approve October 19, 2025 13:40 — with GitHub Actions Failure

Unshure had a problem deploying to auto-approve October 19, 2025 14:09 — with GitHub Actions Failure

Unshure had a problem deploying to auto-approve October 19, 2025 14:13 — with GitHub Actions Failure

Unshure temporarily deployed to auto-approve October 19, 2025 14:19 — with GitHub Actions Inactive

awsarron approved these changes Oct 20, 2025

View reviewed changes

dbschmigelski approved these changes Oct 21, 2025

View reviewed changes

Unshure merged commit b69478b into strands-agents:main Oct 21, 2025
16 of 19 checks passed

	def add_tool(tool: Any) -> None:
	# Case 1: String file path
	if isinstance(tool, str):
	# Extract tool name from path
	tool_name = os.path.basename(tool).split(".")[0]
	self.load_tool_from_filepath(tool_name=tool_name, tool_path=tool)
	tool_names.append(tool_name)

	# Case 2: Dictionary with name and path
	elif isinstance(tool, dict) and "name" in tool and "path" in tool:
	self.load_tool_from_filepath(tool_name=tool["name"], tool_path=tool["path"])
	tool_names.append(tool["name"])

	# Case 3: Dictionary with path only
	elif isinstance(tool, dict) and "path" in tool:
	tool_name = os.path.basename(tool["path"]).split(".")[0]
	self.load_tool_from_filepath(tool_name=tool_name, tool_path=tool["path"])
	tool_names.append(tool_name)

	# Case 4: Imported Python module
	elif hasattr(tool, "__file__") and inspect.ismodule(tool):
	# Get the module file path
	module_path = tool.__file__
	# Extract the tool name from the module name
	tool_name = tool.__name__.split(".")[-1]

	# Check for TOOL_SPEC in module to validate it's a Strands tool
	if hasattr(tool, "TOOL_SPEC") and hasattr(tool, tool_name) and module_path:
	self.load_tool_from_filepath(tool_name=tool_name, tool_path=module_path)
	tool_names.append(tool_name)
	else:
	function_tools = self._scan_module_for_tools(tool)
	for function_tool in function_tools:
	self.register_tool(function_tool)
	tool_names.append(function_tool.tool_name)

	if not function_tools:
	logger.warning("tool_name=<%s>, module_path=<%s> \| invalid agent tool", tool_name, module_path)

	# Case 5: AgentTools (which also covers @tool)
	elif isinstance(tool, AgentTool):
	self.register_tool(tool)
	tool_names.append(tool.tool_name)
	# Case 6: Nested iterable (list, tuple, etc.) - add each sub-tool
	elif isinstance(tool, Iterable) and not isinstance(tool, (str, bytes, bytearray)):
	for t in tool:
	add_tool(t)
	else:
	logger.warning("tool=<%s> \| unrecognized tool specification", tool)

Uh oh!

feat: add experimental AgentConfig with comprehensive tool management #935

feat: add experimental AgentConfig with comprehensive tool management #935

Uh oh!

Conversation

mr-lee commented Sep 26, 2025 • edited by Unshure Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Goal of this feature:

Usage example

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

awsarron left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

awsarron left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Unshure commented Oct 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mr-lee commented Sep 26, 2025 •

edited by Unshure

Loading

awsarron left a comment •

edited

Loading

codecov bot commented Oct 8, 2025 •

edited

Loading

awsarron left a comment •

edited

Loading